Skip to main content

Best Practices

Integrating with the Stingray Music API provides a powerful way to enhance your application with a wide range of music streaming capabilities. To ensure an optimal experience for both your users and the Stingray servers, it's important to follow a set of best practices.

These guidelines will help you maintain efficient, stable, and responsible usage of the API.

Rate Limiting​

  • Limit Search Frequency: To maintain a high quality of service for all users, limit the frequency of search requests to no more than one per 100 milliseconds per user. This helps prevent overloading the system with excessive requests.
  • Limit Skip Frequency: For the same reasons, also limit the frequency of station skip to no more than one per 100 milliseconds per user.
Do

Implement client-side throttling to enforce those rate limit.

Don't

Allow back-to-back search requests that exceed the rate limit.

Search Query Optimization​

Minimum Query Length: Avoid sending search requests for queries that are less than three characters long. Short queries are often too broad and can result in unnecessary load on the server.

Do

Implement input validation to ensure that search queries are at least three characters before sending a request.

Don't

Send requests for one or two-character search terms.

Resilience Patterns​

Implement Circuit Breakers: Use the circuit breaker pattern to prevent a cascade of failures and allow the server time to recover. If you detect a pattern of errors or timeouts, temporarily halt further requests and retry after a suitable cool-down period.

Do

Monitor for repeated errors and implement logic to stop requests during API outages or slowdowns.

Don't

Continue to send requests in the face of consistent API failures.

Pagination and Data Retrieval​

Use Smaller Pages: When dealing with endpoints that support pagination, request smaller pages of data. A range of 10-20 items per page is ideal for balancing performance and user experience.

Do

Specify a limit parameter within the recommended range if the API supports it.

Don't

Request large pages of data that can slow down the server response time and your application.

Caching Strategy​

  • Cache API Responses: To improve the responsiveness of your application, a caching strategy can be implemented for API responses. Data such as search results and metadata can be cached.
  • Cache Duration: The data returned from the API can be cached for up to 24 hours. After this period, ensure that your application refreshes the cached content to keep the information up to date.
  • Audio Content: Due to legal restrictions, you must not cache the audio content provided by the Stingray Music API. Always stream audio directly from the API to comply with licensing agreements.
Do
  • Set an expiration time on cached data for a maximum of 24 hours.
  • Stream audio content directly from the API without caching.
Don't
  • Use stale data beyond the recommended cache duration.
  • Store or cache audio files on your servers or client devices.

Summary​

By adhering to these best practices, you can ensure a more sustainable and efficient use of the Stingray Music API. It will help you avoid common pitfalls, reduce the risk of service interruptions, and provide a smoother experience for your users. Remember to always stay updated with the latest API documentation provided by Stingray for any changes or additional recommendations.